=begin pod :kind("Type") :subkind("role") :category("domain-specific")

=TITLE role Scheduler

=SUBTITLE Scheme for automatically assigning tasks to threads

    role Scheduler {
        has &.uncaught_handler is rw
    }

A scheduler is a piece of code that determines which resources to use to run
which task, and when. This role contains code that will be the same for all
kinds of schedulers.

Some operations for example on L<Proc::Async|/type/Proc::Async>,
L<Promise|/type/Promise>, L<Supply|/type/Supply> allow you to specify a
scheduler explicitly; they generally expect those schedulers to follow the
interface defined by C<Scheduler>.

=head1 Methods

=head2 method uncaught_handler

    method uncaught_handler() is rw

RW-Accessor for the handler that is caught for uncaught exceptions from the
code that is being scheduled and run.

=head2 method cue

    method cue(&code, Instant :$at, :$in, :$every, :$times = 1; :&catch --> Cancellation)

Schedules a callable (C<&code>) for execution and returns an instantiated
L<C<Cancellation>|/type/Cancellation> object to cancel the scheduling of the
code for execution (which is especially important if you specify the C<:every
( time )> named parameter). The adverbs control when and how the code is run:

=item C<$at> can be an L<Instant|/type/Instant> before which the code won't be
run.
Alternatively C<$in> is the number of seconds (possibly fractional) to wait
before running the code. If C<$at> is in the past or C<$in> is negative,
the delay is treated as zero. Implementations may equate to zero
very small values (e.g. lower than 0.001s) of C<$in> or result of
C<$at> - L<now|/routine/now>.

=item If C<$every> is specified, it is interpreted as the number of seconds
(possibly fractional) to wait before re-executing the code. Implementations
may treat too-small values as lowest resolution they support, possibly
warning in such situations; e.g. treating C<0.0001> as C<0.001>.

=item C<$times> tells the scheduler how many times to run the code.

=item C<&catch> is called with the L<Exception|/type/Exception> as its sole
argument
if C<&code> dies.

=item If C<$at> or C<$in> are C<Inf>, C<&code> will never be run; if
C<$every> is
C<Inf>, C<&code> will only be run once. If any of the three are C<-Inf>,
C<&code> will be run immediately. If any of the three are C<NaN>, an
L<X::Scheduler::CueInNaNSeconds|/type/X::Scheduler::CueInNaNSeconds> exception
will be thrown. This only applies to releases 2019.05 and later.

One should call the C<cancel> method on the returned C<Cancellation> object
to cancel the (possibly repeated) cueing of the code.

=head2 method loads

Defined as:

    method loads()

This is a method stub, should be re-implemented when subclassing.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
